Provision Calling Profile Templates

Calling Profile templates allow you to apply Calling Profiles when applying license (see Create Service from Lead Overview), adding SIP Connections (see Add SIP Connections), uploading (see Upload Operator Connect Numbers to Customer) and releasing numbers (see Release Operator Connect Numbers from Customer). When adding SIP Connections with Advanced configuration, an IP Group is added for each connection on the configured SBC device. The IP Group represents a SIP entity in Live Platform that is used to configure SIP calling and routing functionality. For example, classifying incoming SIP dialog-initiating requests in INVITE messages, configuring SIP dialog-initiating requests, call routing rules, and Quality of Experience features. You can then assign each Calling Profile template to a different IP Group. For instance, you might want to configure an IP Group with enhanced security settings based on the site location's topology requirements and map it to a Calling Profile tailored for a specific carrier.

Provisioning is performed asynchronously by the ProvisionCallingProfileTemplateWorkflow background workflow, which configures the customer's telephony connection (e.g., SBC scripts, proxy sets, CAC profiles) according to the template and the supplied script parameters. The endpoint initially returns a task identifier that you must then query to confirm finality.

HTTP Method

POST

URI

Copy 
{{baseUrl}}api/v3/customer/{customerGuid}/action/provisionCallingProfileTemplate

Configuration rules

■ The customer identified by customerGuid must exist.
■ The AssignmentLabel (Connection Name) must be unique per customer. Comparison is case-insensitive and ignores leading/trailing whitespace.
■ The CallingProfileTemplateId must reference a Calling Profile Template that is configured and available in the system; the template is validated by the workflow.

When the request originates from Live Platform portal, the Live Platform portal user identity is propagated to the workflow for auditing purposes; otherwise the authenticated caller's identity is used.

Validation rules

■ CallingProfileTemplateId: required, maximum 150 characters.
■ AssignmentLabel: required, maximum 250 characters, trimmed before uniqueness check.
■ Description: required, maximum 500 characters.
■ ScriptParameters: optional dictionary of template-specific key/value parameters consumed by the provisioning scripts (e.g., proxy set, CAC profile, carrier credentials). The set of valid parameters depends on the selected template.

Request Parameter

Parameter

Type

Description

CustomerGuid

string ($uuid)

The CustomerGuid created in the Live Platformcustomer tenant SQL database. A new OC Essentials service is created when a license is applied to the lead using Create Service from Lead Overview). If this field is null, a license has not yet been applied to the lead.

Request Body

Parameter

Type

Description

callingProfileTemplateId

integer

The Id of the Calling Profile Template record that is attached to the tenant service. Calling Profile Provisioning templates allow you to apply Calling Profile Templates when applying license (see Create OC Essential Service from Lead with IP Group), adding OC SIP Connections (see Add SIP Connections), uploading numbers (see Upload Operator Connect Numbers to Customer) and releasing numbers (see Release Operator Connect Numbers from Customer). You can then assign each Calling Profile Provisioning template to a different IP Group. For instance, you might want to configure an IP Group with enhanced security settings based on the site location's topology requirements and map it to a Calling Profile tailored for a specific carrier.

● This value is assigned to services with IP Group-based SIP Connections.
● This value cannot be extracted using the API, instead extract it from the Multitenant Web interface.

assignmentLabel

string

Arbitrary text value to identify the Calling Profile Template Id.

scriptParameters refers to:

CustomVar.Variable<VariableSequenceNumber>

dictionary

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■ CustomVar.Variable1: <: IPPBX-ProxyAddress>
■ CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>
■ CustomVar.Variable3: <SIP-HostName>

 

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

There are three fields displayed in the schema additionalProp1-3, however there is no limitation for the number of variables that can be added.

additionalProp1

CustomVar.Variable<VariableSequenceNumber>

string

For example, Proxy Set name

additionalProp2

CustomVar.Variable<VariableSequenceNumber>

string

For example, CAC Profile value

additionalProp3

CustomVar.Variable<VariableSequenceNumber>

string

For example, OnlinePstnGateway name

Example Request

Copy 
  {
  "callingProfileTemplateId": "OperatorConnect-Default",
  "assignmentLabel": "Contoso-Primary",
  "description": "Primary calling profile for Contoso operator connect deployment",
  "scriptParameters": {
    "ProxySet": "ProxySet_1",
    "CacProfile": "CAC_Default",
    "OnlinePstnGateway": "sbc1.contoso.com"
  }
}          

Example Response

Copy 
{
  "taskId": "wcptp_12345"
}
            

 

● The returned TaskId uses the wcptp_ prefix and may be polled at /api/v2/task/{taskId} to retrieve workflow status, execution messages, and output data.
● Provisioning is performed asynchronously, an HTTP 202 response indicates only that the workflow has successfully started; failures occurring during provisioning (e.g., template validation, SBC configuration) are described in the task status endpoint.
● The set of valid ScriptParameters keys is defined by the selected Calling Profile Template; supplying unknown keys may be ignored or cause the workflow to fail depending on the template.

Responses

■ 202 Accepted

Parameters

Type

Description

callingProfileTemplateId

string

Name of the Calling Profile Template ID. For example, OperatorConnect-Default.

scriptParameters
■ additionalProp1 string
■ additionalProp2 string
■ additionalProp3 string

One of the following values:

■ SBC name (Provider SIP Trunk, BYOC or IP-PBX)
■ Region name
■ Carrier name

additionalProp1

CustomVar.Variable<VariableSequenceNumber>

string

Proxy Set name. For example, "SIP Trunk"

additionalProp2

CustomVar.Variable<VariableSequenceNumber>

string

CAC Profile value. For example, "4 sessions"

additionalProp3

CustomVar.Variable<VariableSequenceNumber>

string

OnlinePstnGateway name. For example, sbc1.contoso.com.
■ 400 Bad Request

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id.

instance

string

Error instance.

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 403 Forbidden
■ 404 Not Found
■ 500 Internal Server Error